<!-- HTML header for doxygen 1.8.3.1-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.3.1"/>
<title>Sifteo SDK: Debugging</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="doxygen-style-overrides.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<center>
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Sifteo SDK" src="sdk_logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">
   &#160;<span id="projectnumber">v1.0.0</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
</center>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.3.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Home</span></a></li>
      <li class="current"><a href="pages.html"><span>Guides</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li><a href="annotated.html"><span>Reference</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Classes</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

</div><!-- top -->
<div class="header">
  <div class="headertitle">
<div class="title">Debugging </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>Tips for debugging your games</p>
<p>Unfortunately, it's inevitable - bugs will find their way into your game. Never fear! Let's go over some of the strategies available for hunting them down.</p>
<h1>Logging</h1>
<p>The simplest form of debugging available is <a class="el" href="group__macros.html#ga3577749fb48d57a158b8ac1a0b3ab57e" title="Smart printf-like logging macro.">LOG()</a> and its friends in the <a class="el" href="group__macros.html">Macros</a> module. This allows you to render values in your application according to a given format string, similar to <a href="http://www.cplusplus.com/reference/cstdio/printf">printf()</a>.</p>
<h2>Simulation</h2>
<p>In simulation, the output from <a class="el" href="group__macros.html#ga3577749fb48d57a158b8ac1a0b3ab57e" title="Smart printf-like logging macro.">LOG()</a> is written directly to the console.</p>
<p>You can redirect the output to a file by invoking siftulator with the <code>--stdout</code> option, as follows: </p>
<pre class="fragment">$ siftulator awesome-game.elf --stdout mylogfile.txt
</pre><h2>Hardware</h2>
<p>On hardware, there's of course no console to write to. Instead, <code>swiss listen</code> can capture console output from the Sifteo Base over a USB connection.</p>
<p>To be as efficient as possible, the Base sends only the bare minimum of log info over the USB connection, then <code>swiss</code> is responsible for accessing your game's .elf and decoding the log info accordingly.</p>
<p>This means you must provide the same elf running on the Base to <code>swiss listen</code>, as follows: </p>
<pre class="fragment">$ swiss listen awesome-game.elf
</pre><p>Your <a class="el" href="group__macros.html#ga3577749fb48d57a158b8ac1a0b3ab57e" title="Smart printf-like logging macro.">LOG()</a> statements will be rendered to the console, and should look the same as when printed by siftulator.</p>
<p>See the <a class="el" href="device_mgmt.html">Device Management</a> guide for more details on how to use <code>swiss</code>.</p>
<h1>Capturing Fault Logs</h1>
<p>When a fault occurs while your app is running, the Sifteo Base stores an internal record describing details of the fault, and displays the dreaded Cat Monkey.</p>
<div class="image">
<img src="cat-monkey.png" alt="cat-monkey.png"/>
<div class="caption">
Cat monkey is not pleased</div></div>
<p> The <b>Ref#</b> in the fault display is not an error code, but an instance ID that allows you to distinguish a particular instance of an error from others that might be similar.</p>
<p>All the helpful details are stored internally in fault logs on the Base. Use the <code>swiss savedata</code> command, specifying <code>com.sifteo.syslfs</code> to retrieve the Base's internal savedata: </p>
<pre class="fragment">$ swiss savedata extract com.sifteo.syslfs my-fault-records.bin
</pre><p>Now, use the python script in the sdk/tools directory to interpret syslfs.bin: </p>
<pre class="fragment">$ python sdk/tools/savedata.py my-fault-records.bin
</pre><p>Sample output: </p>
<pre class="fragment">Fault Info for com.mycompany.mygame (0.3.0)
    uuid: f8531629-3539-42aa-8d54-b9b20e824292
Header Info
    reference: 2
    recordType: 1 - SVM Fault Record
    runningVolume: 0xb
    fault code: 0xe - User call to _SYS_abort
    uptime (in sys ticks): 30627379585
CubeInfo
    num connected to the system (bitmap): 0xf0000000
    num visible to user space (bitmap): 0xf0000000
    cube range: 3 - 8
Registers
    PC: 0x8000030e
    SP: 0x2000fab8
    FP: 0x2000fab8
    r0: 0x20003f40
    r1: 0x20002680
    r2: 0x3d0e5532
    r3: 0xffffffff
    r4: 0x00000000
    r5: 0x00000007
    r6: 0x21704fb2
    r7: 0x00000003
</pre><p>This shows us that <b>com.mycompany.mygame</b>, version <b>0.3.0</b>, was responsible for generating fault code <b>0xe</b>, which indicates a call to _SYS_abort(). This fault was <b>Ref #2</b>, so if this same fault had happened several times, we'd have a way to determine which is which.</p>
<dl class="section note"><dt>Note</dt><dd>If you don't have python installed on your machine, <a href="http://python.org/download">http://python.org/download</a> should point you in the right direction.</dd></dl>
<h2>PC Lookup</h2>
<p>In the <b>Registers</b> section above, PC is short for <b>program counter</b>, which is the register that holds the address of the instruction being executed at any given moment. We can cross reference the PC from the fault log with your game's .elf to see what was executing when the fault was generated.</p>
<p>To do this, you'll need to install the ARM GCC toolchain available at <a href="https://launchpad.net/gcc-arm-embedded">https://launchpad.net/gcc-arm-embedded</a>. Once this is installed, you can run a command like the following: </p>
<pre class="fragment">$ arm-none-eabi-objdump -d awesome-game.elf | arm-none-eabi-c++filt -n | less
</pre><p>You'll be presented with the disassembly of your game, with the addresses in the column on the left, and function names interleaved to indicate where they begin. Scroll through the output until you find the PC address, and you should have your culprit!</p>
<dl class="section note"><dt>Note</dt><dd>On Windows, <code>less</code> may not be available by default, but can be installed via <a href="http://www.mingw.org">http://www.mingw.org</a>. Future SDKs will likely have a more streamlined approach for this process.</dd></dl>
<h1>Source Level Debugging</h1>
<p>We have plans to introduce GDB-compatible source level debugging in a future release, but this is not yet available. Stand by! </p>
</div></div><!-- contents -->
<!-- HTML footer for doxygen 1.8.3.1-->
<!-- start footer part -->
    <hr class="footer"/>
    <address class="footer">
        <p><a href="http://sifteo.com">Sifteo</a> SDK v1.0.0 <small>(see <a href="https://developers.sifteo.com/sifteosdk">all versions</a>)</small></p>
        <p>Last updated Wed Mar 27 2013, by <a href="http://www.stack.nl/~dimitri/doxygen">Doxygen</a></p>
    </address>
</body>
</html>
